[COPYRIGHT © 2024 RIBBON COMMUNICATIONS OPERATING COMPANY, INC. ALL RIGHTS RESERVED]: # # Subscription-Related Events Note: This tutorial is for the SDK's event-driven APIs, namely `setCredentials`, `services.subscribe` and `services.unsubscribe`. When using the SDK's Async APIs, only a subset of these events are emitted. Specifically, only the `auth:error`, `ws:change`, and `subscription:change` events. Feedback covered by the other events are instead provided via the returned promise from the API. Please see the [Async APIs](Async%20APIs) tutorial for more information. This tutorial will cover three subscription-related event categories: authentication, connectivity, and subscription. It will list the events in each category, explain when they are emitted, explain what they mean, and provide information on how an application can/should handle them when encountered. For more details on the error-specific events, see the other trail page titled [Handling Subscription Errors](Handling%20Subscription%20Errors). ## Authentication Events The authentication events are relevant only for the setting of the user credentials. The following table lists the authentication events, a summary of their descriptions, and a recommendation on how to handle them. | Event|Event payload|Event description|Event Handling| | --------- | ---------- | ------------- | --------- | |auth:change|N/A| The authentication credentials have been set. You can check the set user details with the `getUserInfo` API.|This event is emitted when setting user credentials. To see the updated user info, use the `getUserInfo` API.| |auth:error|{
  error: BasicError
}

|There was an error with authentication.

All "authentication:x" errors are documented in [Handling Subscription Errors](Handling%20Subscription%20Errors) tutorial trail.|For handling, refer to the Handling Subscription Errors tutorial trail.| ## Connectivity Events The connectivity events are related to the WebSocket connection created with the server. The following table lists the connectivity events, a summary of their descriptions, and a recommendation on how to handle them. | Event|Event payload|Event description|Event Handling| | --------- | ---------- | ------------- | --------- | |ws:change|{}|The websocket connection to the server has changed state.

This event is emitted when:
  1. The `WebSocket` has connected
  2. The `WebSocket` lost connection


Note: this event is not emitted when the WS is closed|You can check the state of the `WebSocket` using the `connection.getSocketState` API.

You may also try resetting the connection using the `connection.resetConnection` API. This event could also be used by an application to show connection progress on a UI (e.g., from `connecting` to `connected`).| ## Subscription Events Subscription events refer to the events surrounding subscription of a user to services. They cover when subscriptions are made, when subscriptions are lost, or when any errors occur. The following table lists the subscription events, a summary of their descriptions, and a recommendation on how to handle them. | Event|Event payload|Event description|Event Handling| | --------- | ---------- | ------------- | --------- | |subscription:change|{
  reason: String
}

Reasons can be:
  • 'PENDING'
  • 'SUBSCRIBED'
  • 'UNSUBSCRIBED'
  • 'LOST_CONNECTION'
  • 'GONE'
  • 'WS_OVERRIDDEN'
|The subscription information has changed.

`params.reason` - When solicited, the reason for the change.
  • 'PENDING' - The subscription request has been made.
  • 'SUBSCRIBED' - The user has been subsribed to services.
  • 'UNSUBSCRIBED' - The user has been unsubscribed from services.

When you receive a `subscription:change` event outside of an explicit subscription request.

`params.reason` can have these values:
  • 'GONE' - When Connection was terminated by the server.
  • 'LOST_CONNECTION' - When internet connection was lost.
  • 'WS_OVERRIDDEN' - When websocket was overridden by the server.
|The current subscription state can be fetched using the `services.getSubscriptions` API and then understood using the `isPending` and `subscribed` attributes.

Typically, upon making a subscription request there will be two subscription events emitted. The first event (`subscription:change`) will be emitted with a `reason` of `PENDING` which is to indicate that the `isPending` flag is now set to true. The second event `subscription:change` with `reason` `SUBSCRIBED` OR `UNSUBSCRIBED` if succesful or `subscription:error` if there was a problem, will indicate the result of the subscription request.

The `isPending` flag is set to true when a subscription request has been made (for example, to subscribe a user or unsubscribe a user). An application can make use of this event to update the UI to let users know that a request is made and currently pending.

When `isPending` is false, this means that the subscription change has completed, and the subscribed array will contain the list of services subscribed to. If the list is empty, this means the user is not subscribed.

In the event of an unsolicited error (e.g., server/internet issues), the `reason` parameter in the event's payload will indicate the cause of the failure.

An application can attempt to re-subscribe a user if a reason argument is provided in the event payload with `GONE` or `LOST_CONNECTION`, similarly to instructors provided in the [Handling Subscription Errors](Handling%20Subscription%20Errors) tutorial.

NOTE: This event is not emitted after a subscription request failure (see `subscription:error` event).| |subscription:error|{
  error: BasicError
}|An error occurred during a subscription operation.

The subscription information can be retrieved using the `services.getSubscriptions` API.

Some common errors related to service subscriptions are summarized in [Handling Subscription Errors](Handling%20Subscription%20Errors)|For handling, see the [Handling Subscription Errors](Handling%20Subscription%20Errors) tutorial.| |subscription:resub|{
  attemptNum: X,
  isFailure:Boolean,
  error: BasicError
}|An attempt to extend the current user's subscription was made.

In a failure scenario, the current user is still connected, and further resubscription attempts will be made, but may become disconnected if the session expires.|No handling required, the SDK is attempting to resubscribe.| [COPYRIGHT © 2024 RIBBON COMMUNICATIONS OPERATING COMPANY, INC. ALL RIGHTS RESERVED]: #